Add env and env_file support to machine configuration by tuler · Pull Request #498 · cartesi/cli

tuler · 2026-06-30T18:42:14Z

Motivation

Environment variables are typically used to differentiate between multiple build or test scenarios. One classic examples are testnet vs devnet vs mainnet, but there may be other scenarios.

Currently the build process only supports environment variables defined inside the Dockerfile used by the cartesi build process. But the same variables defined in the Dockerfile may be necessary outside the cartesi build process. For example in a host build process that is not related to the cartesi build process at all. So in this case there is a duplication of environment variables values, which hurts maintenance.

By having .env files support we can maintain a single source of truth for environment variables and use it in both the cartesi build workflow and other workflows.

Summary

This PR adds support for injecting environment variables into the Cartesi Machine through two new configuration options in the [machine] section of cartesi.toml: an env table for inline key/value pairs and an env_file option pointing to a .env file.

Key Changes

New configuration options: Added env (Record<string, string>) and envFile (optional string) to MachineConfig
TOML parsing: Implemented parseStringRecord() to parse TOML tables into environment variable records, with automatic coercion of non-string scalar values (numbers, booleans) to strings
.env file parsing: Added parseEnvFile() function that parses .env files with support for:
- Blank lines and # comments
- Optional export prefix
- Single/double quoted values
- Whitespace trimming
- Preservation of = signs in values
Environment variable precedence: Updated bootMachine() to merge environment variables with proper precedence (lowest to highest):
1. Docker image ENV (when use_docker_env is enabled)
2. Variables from env_file
3. Variables from the env table
Error handling: Added InvalidEnvError exception class for invalid env configurations
Comprehensive tests: Added unit tests covering all parsing scenarios and edge cases

Implementation Details

Environment variables are merged into a single map before being passed to cartesi-machine, allowing later sources to override earlier ones
The .env file parser is robust and handles common .env file formats
Non-string values in the env table are automatically converted to strings since environment variables are always strings
The implementation maintains backward compatibility with existing configurations

https://claude.ai/code/session_016vnD51QAGwAvqaZuEZJypr

changeset-bot · 2026-06-30T18:42:17Z

🦋 Changeset detected

Latest commit: a6f9068

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@cartesi/cli	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2026-06-30T18:46:01Z

Coverage Report

Status	Category	Percentage	Covered / Total
🟢	Lines	98.82% (🎯 0%)	4851 / 4909
🔵	Statements	98.82%	4851 / 4909
🔵	Functions	96.3%	130 / 135
🔵	Branches	0%	0 / 0

📁 File Coverage (19 files)

File	Lines	Statements	Functions	Branches	Uncovered Lines
`apps/cli/src/builder/directory.ts`	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
`apps/cli/src/builder/docker.ts`	🟢 88.68%	🟢 88.68%	🟡 75%	🔴 0%	83-85, 139-147
`apps/cli/src/builder/empty.ts`	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
`apps/cli/src/builder/none.ts`	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
`apps/cli/src/builder/tar.ts`	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
`apps/cli/src/compose/builder.ts`	🟢 99.79%	🟢 99.79%	🟢 100%	🔴 0%	228
`apps/cli/src/compose/common.ts`	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
`apps/cli/src/compose/node.ts`	🟢 99.24%	🟢 99.24%	🟢 100%	🔴 0%	106
`apps/cli/src/config.ts`	🟢 94.32%	🟢 94.32%	🟢 95.24%	🔴 0%	75-76, 251, 260, 269, 363, ...
`apps/cli/src/contracts.ts`	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
`...rc/errors/ForkChainValidationError.ts`	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
`...c/errors/UnsupportedForkChainError.ts`	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
`...c/exec/cartesi-machine-stored-hash.ts`	🟢 92.86%	🟢 92.86%	🟢 100%	🔴 0%	36-37
`apps/cli/src/exec/cartesi-machine.ts`	🟡 75%	🟡 75%	🟡 66.67%	🔴 0%	10-12, 28-30
`apps/cli/src/exec/genext2fs.ts`	🟢 96.92%	🟢 96.92%	🟢 100%	🔴 0%	87-88
`apps/cli/src/exec/index.ts`	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-
`apps/cli/src/exec/mksquashfs.ts`	🟢 91.23%	🟢 91.23%	🟢 100%	🔴 0%	68-72
`apps/cli/src/exec/util.ts`	🟢 94.74%	🟢 94.74%	🟢 100%	🔴 0%	49-50
`apps/cli/src/validations.ts`	🟢 100%	🟢 100%	🟢 100%	🔴 0%	-

brunomenezes · 2026-07-01T11:03:48Z

+                envMap[variable] = "";
+            } else {
+                envMap[variable.slice(0, eq)] = variable.slice(eq + 1);
+            }


@tuler,
These slices are odd. Could it be done by using a destructuring based on the assumptions of the variable content?

e.g.

const [key, value=""] = variable.split("="); envMap[key] = value;

brunomenezes · 2026-07-01T11:06:28Z

The PR description is strongly on the "how", but I don't understand clearly the "why". Does it help solve an issue Lyno opened?

New Options to cartesi.toml #477

Allow injecting environment variables into the Cartesi Machine build beyond the Dockerfile ENV controlled by use_docker_env: - env: an inline table of key/value pairs in [machine.env] - env_file: a path to a .env file Precedence (lowest to highest): docker image ENV (when use_docker_env is enabled), env_file, then the env table. Also fixes a latent bug where env values containing "=" were truncated at the first "=". Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016vnD51QAGwAvqaZuEZJypr

tuler · 2026-07-01T13:33:34Z

The PR description is strongly on the "how", but I don't understand clearly the "why".

Added a motivation section to the PR description.

brunomenezes · 2026-07-03T10:40:59Z

+
+# [machine.env] # optional. environment variables injected into the machine
+# FOO = "bar"
+# LOG_LEVEL = "debug"


@tuler,
I am curious and just trying to understand how to use it. Is the idea to plug in anything from the environment variable, like arbitrary values that only make sense to what is running inside, or is it to change the behaviour of the machine, like the rollups_node env vars? If the latter would be good to have a list of behaviour-changing ones as they're specific and "reserved" in some sense.

PS: When I build dapps, the default configurations so far work for me, so I am trying to grasp the use. Even though you mentioned the motivation as the workflows and tests on different nets (dev, test ,main), it is not clear to me what these cases are; I mean what users are actually doing.

it's for any arbitrary env var the application may use to configure the application logic.
examples for a financial application:
COLLATERAL_TOKEN_ADDRESS
PRICE_FEED_ADDRESS

github-project-automation Bot added this to Rollups SDK Jun 30, 2026

github-project-automation Bot moved this to Todo in Rollups SDK Jun 30, 2026

brunomenezes reviewed Jul 1, 2026

View reviewed changes

tuler force-pushed the claude/cartesi-toml-env-config-cdo0ay branch from 683a9eb to a6f9068 Compare July 1, 2026 13:27

tuler marked this pull request as ready for review July 1, 2026 13:34

brunomenezes reviewed Jul 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add env and env_file support to machine configuration#498

Add env and env_file support to machine configuration#498
tuler wants to merge 1 commit into
prerelease/v2-alphafrom
claude/cartesi-toml-env-config-cdo0ay

tuler commented Jun 30, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

brunomenezes Jul 1, 2026

Uh oh!

brunomenezes commented Jul 1, 2026

Uh oh!

tuler commented Jul 1, 2026

Uh oh!

brunomenezes Jul 3, 2026

Uh oh!

tuler Jul 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

tuler commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Summary

Key Changes

Implementation Details

Uh oh!

changeset-bot Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report

Uh oh!

brunomenezes Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

brunomenezes commented Jul 1, 2026

Uh oh!

tuler commented Jul 1, 2026

Uh oh!

brunomenezes Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

tuler Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tuler commented Jun 30, 2026 •

edited

Loading

changeset-bot Bot commented Jun 30, 2026 •

edited

Loading

github-actions Bot commented Jun 30, 2026 •

edited

Loading